<!DOCTYPE html>

<html>
  <head>
    <meta charset="utf-8">
    
    <title>What is NumPy? &mdash; NumPy v1.18 Manual</title>
    
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-bootstrap.css">
    <link rel="stylesheet" type="text/css" href="../_static/css/spc-extend.css">
    <link rel="stylesheet" href="../_static/scipy.css" type="text/css" >
    <link rel="stylesheet" href="../_static/pygments.css" type="text/css" >
    <link rel="stylesheet" href="../_static/graphviz.css" type="text/css" >
    
    <script type="text/javascript">
      var DOCUMENTATION_OPTIONS = {
        URL_ROOT:    '../',
        VERSION:     '1.18.1',
        COLLAPSE_INDEX: false,
        FILE_SUFFIX: '.html',
        HAS_SOURCE:  false
      };
    </script>
    <script type="text/javascript" src="../_static/jquery.js"></script>
    <script type="text/javascript" src="../_static/underscore.js"></script>
    <script type="text/javascript" src="../_static/doctools.js"></script>
    <script type="text/javascript" src="../_static/language_data.js"></script>
    <script type="text/javascript" src="../_static/js/copybutton.js"></script>
    <link rel="author" title="About these documents" href="../about.html" >
    <link rel="index" title="Index" href="../genindex.html" >
    <link rel="search" title="Search" href="../search.html" >
    <link rel="top" title="NumPy v1.18 Manual" href="../index.html" >
    <link rel="up" title="Setting up" href="setting-up.html" >
    <link rel="next" title="Installing NumPy" href="install.html" >
    <link rel="prev" title="Setting up" href="setting-up.html" > 
  </head>
  <body>
<div class="container">
  <div class="top-scipy-org-logo-header" style="background-color: #a2bae8;">
    <a href="../index.html">
      <img border=0 alt="NumPy" src="../_static/numpy_logo.png"></a>
    </div>
  </div>
</div>


    <div class="container">
      <div class="main">
        
	<div class="row-fluid">
	  <div class="span12">
	    <div class="spc-navbar">
              
    <ul class="nav nav-pills pull-left">
        <li class="active"><a href="https://numpy.org/">NumPy.org</a></li>
        <li class="active"><a href="https://numpy.org/doc">Docs</a></li>
        
        <li class="active"><a href="../index.html">NumPy v1.18 Manual</a></li>
        

          <li class="active"><a href="index.html" >NumPy User Guide</a></li>
          <li class="active"><a href="setting-up.html" accesskey="U">Setting up</a></li> 
    </ul>
              
              
    <ul class="nav nav-pills pull-right">
      <li class="active">
        <a href="../genindex.html" title="General Index"
           accesskey="I">index</a>
      </li>
      <li class="active">
        <a href="install.html" title="Installing NumPy"
           accesskey="N">next</a>
      </li>
      <li class="active">
        <a href="setting-up.html" title="Setting up"
           accesskey="P">previous</a>
      </li>
    </ul>
              
	    </div>
	  </div>
	</div>
        

	<div class="row-fluid">
      <div class="spc-rightsidebar span3">
        <div class="sphinxsidebarwrapper">
  <h3><a href="../contents.html">Table of Contents</a></h3>
  <ul>
<li><a class="reference internal" href="#">What is NumPy?</a><ul>
<li><a class="reference internal" href="#why-is-numpy-fast">Why is NumPy Fast?</a></li>
<li><a class="reference internal" href="#who-else-uses-numpy">Who Else Uses NumPy?</a></li>
</ul>
</li>
</ul>

  <h4>Previous topic</h4>
  <p class="topless"><a href="setting-up.html"
                        title="previous chapter">Setting up</a></p>
  <h4>Next topic</h4>
  <p class="topless"><a href="install.html"
                        title="next chapter">Installing NumPy</a></p>
<div id="searchbox" style="display: none" role="search">
  <h4>Quick search</h4>
    <div>
    <form class="search" action="../search.html" method="get">
      <input type="text" style="width: inherit;" name="q" />
      <input type="submit" value="search" />
      <input type="hidden" name="check_keywords" value="yes" />
      <input type="hidden" name="area" value="default" />
    </form>
    </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
        </div>
      </div>
          <div class="span9">
            
        <div class="bodywrapper">
          <div class="body" id="spc-section-body">
            
  <div class="section" id="what-is-numpy">
<h1>What is NumPy?<a class="headerlink" href="#what-is-numpy" title="Permalink to this headline">¶</a></h1>
<p>NumPy is the fundamental package for scientific computing in Python.
It is a Python library that provides a multidimensional array object,
various derived objects (such as masked arrays and matrices), and an
assortment of routines for fast operations on arrays, including
mathematical, logical, shape manipulation, sorting, selecting, I/O,
discrete Fourier transforms, basic linear algebra, basic statistical
operations, random simulation and much more.</p>
<p>At the core of the NumPy package, is the <em class="xref py py-obj">ndarray</em> object.  This
encapsulates <em>n</em>-dimensional arrays of homogeneous data types, with
many operations being performed in compiled code for performance.
There are several important differences between NumPy arrays and the
standard Python sequences:</p>
<ul class="simple">
<li><p>NumPy arrays have a fixed size at creation, unlike Python lists
(which can grow dynamically). Changing the size of an <em class="xref py py-obj">ndarray</em> will
create a new array and delete the original.</p></li>
<li><p>The elements in a NumPy array are all required to be of the same
data type, and thus will be the same size in memory.  The exception:
one can have arrays of (Python, including NumPy) objects, thereby
allowing for arrays of different sized elements.</p></li>
<li><p>NumPy arrays facilitate advanced mathematical and other types of
operations on large numbers of data.  Typically, such operations are
executed more efficiently and with less code than is possible using
Python’s built-in sequences.</p></li>
<li><p>A growing plethora of scientific and mathematical Python-based
packages are using NumPy arrays; though these typically support
Python-sequence input, they convert such input to NumPy arrays prior
to processing, and they often output NumPy arrays.  In other words,
in order to efficiently use much (perhaps even most) of today’s
scientific/mathematical Python-based software, just knowing how to
use Python’s built-in sequence types is insufficient - one also
needs to know how to use NumPy arrays.</p></li>
</ul>
<p>The points about sequence size and speed are particularly important in
scientific computing.  As a simple example, consider the case of
multiplying each element in a 1-D sequence with the corresponding
element in another sequence of the same length.  If the data are
stored in two Python lists, <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code>, we could iterate over
each element:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">c</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">a</span><span class="p">)):</span>
    <span class="n">c</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">*</span><span class="n">b</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>
</pre></div>
</div>
<p>This produces the correct answer, but if <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> each contain
millions of numbers, we will pay the price for the inefficiencies of
looping in Python.  We could accomplish the same task much more
quickly in C by writing (for clarity we neglect variable declarations
and initializations, memory allocation, etc.)</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">rows</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">):</span> <span class="p">{</span>
  <span class="n">c</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">=</span> <span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="p">]</span><span class="o">*</span><span class="n">b</span><span class="p">[</span><span class="n">i</span><span class="p">];</span>
<span class="p">}</span>
</pre></div>
</div>
<p>This saves all the overhead involved in interpreting the Python code
and manipulating Python objects, but at the expense of the benefits
gained from coding in Python.  Furthermore, the coding work required
increases with the dimensionality of our data. In the case of a 2-D
array, for example, the C code (abridged as before) expands to</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">for</span> <span class="p">(</span><span class="n">i</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">i</span> <span class="o">&lt;</span> <span class="n">rows</span><span class="p">;</span> <span class="n">i</span><span class="o">++</span><span class="p">):</span> <span class="p">{</span>
  <span class="k">for</span> <span class="p">(</span><span class="n">j</span> <span class="o">=</span> <span class="mi">0</span><span class="p">;</span> <span class="n">j</span> <span class="o">&lt;</span> <span class="n">columns</span><span class="p">;</span> <span class="n">j</span><span class="o">++</span><span class="p">):</span> <span class="p">{</span>
    <span class="n">c</span><span class="p">[</span><span class="n">i</span><span class="p">][</span><span class="n">j</span><span class="p">]</span> <span class="o">=</span> <span class="n">a</span><span class="p">[</span><span class="n">i</span><span class="p">][</span><span class="n">j</span><span class="p">]</span><span class="o">*</span><span class="n">b</span><span class="p">[</span><span class="n">i</span><span class="p">][</span><span class="n">j</span><span class="p">];</span>
  <span class="p">}</span>
<span class="p">}</span>
</pre></div>
</div>
<p>NumPy gives us the best of both worlds: element-by-element operations
are the “default mode” when an <em class="xref py py-obj">ndarray</em> is involved, but the
element-by-element operation is speedily executed by pre-compiled C
code.  In NumPy</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">c</span> <span class="o">=</span> <span class="n">a</span> <span class="o">*</span> <span class="n">b</span>
</pre></div>
</div>
<p>does what the earlier examples do, at near-C speeds, but with the code
simplicity we expect from something based on Python. Indeed, the NumPy
idiom is even simpler!  This last example illustrates two of NumPy’s
features which are the basis of much of its power: vectorization and
broadcasting.</p>
<div class="section" id="why-is-numpy-fast">
<span id="whatis-vectorization"></span><h2>Why is NumPy Fast?<a class="headerlink" href="#why-is-numpy-fast" title="Permalink to this headline">¶</a></h2>
<p>Vectorization describes the absence of any explicit looping, indexing,
etc., in the code - these things are taking place, of course, just
“behind the scenes” in optimized, pre-compiled C code.  Vectorized
code has many advantages, among which are:</p>
<ul class="simple">
<li><p>vectorized code is more concise and easier to read</p></li>
<li><p>fewer lines of code generally means fewer bugs</p></li>
<li><p>the code more closely resembles standard mathematical notation
(making it easier, typically, to correctly code mathematical
constructs)</p></li>
<li><p>vectorization results in more “Pythonic” code. Without
vectorization, our code would be littered with inefficient and
difficult to read <code class="docutils literal notranslate"><span class="pre">for</span></code> loops.</p></li>
</ul>
<p>Broadcasting is the term used to describe the implicit
element-by-element behavior of operations; generally speaking, in
NumPy all operations, not just arithmetic operations, but
logical, bit-wise, functional, etc., behave in this implicit
element-by-element fashion, i.e., they broadcast.  Moreover, in the
example above, <code class="docutils literal notranslate"><span class="pre">a</span></code> and <code class="docutils literal notranslate"><span class="pre">b</span></code> could be multidimensional arrays of the
same shape, or a scalar and an array, or even two arrays of with
different shapes, provided that the smaller array is “expandable” to
the shape of the larger in such a way that the resulting broadcast is
unambiguous. For detailed “rules” of broadcasting see
<a class="reference internal" href="basics.broadcasting.html#module-numpy.doc.broadcasting" title="numpy.doc.broadcasting"><code class="xref py py-obj docutils literal notranslate"><span class="pre">numpy.doc.broadcasting</span></code></a>.</p>
</div>
<div class="section" id="who-else-uses-numpy">
<h2>Who Else Uses NumPy?<a class="headerlink" href="#who-else-uses-numpy" title="Permalink to this headline">¶</a></h2>
<p>NumPy fully supports an object-oriented approach, starting, once
again, with <em class="xref py py-obj">ndarray</em>.  For example, <em class="xref py py-obj">ndarray</em> is a class, possessing
numerous methods and attributes.  Many of its methods are mirrored by
functions in the outer-most NumPy namespace, allowing the programmer
to code in whichever paradigm they prefer. This flexibility has allowed the
NumPy array dialect and NumPy <em class="xref py py-obj">ndarray</em> class to become the <em>de-facto</em> language
of multi-dimensional data interchange used in Python.</p>
</div>
</div>


          </div>
        </div>
          </div>
        </div>
      </div>
    </div>

    <div class="container container-navbar-bottom">
      <div class="spc-navbar">
        
      </div>
    </div>
    <div class="container">
    <div class="footer">
    <div class="row-fluid">
    <ul class="inline pull-left">
      <li>
        &copy; Copyright 2008-2019, The SciPy community.
      </li>
      <li>
      Last updated on Feb 20, 2020.
      </li>
      <li>
      Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 2.4.2.
      </li>
    </ul>
    </div>
    </div>
    </div>
  </body>
</html>